<!--
  ~ Copyright (C) 2010 Brockmann Consult GmbH (info@brockmann-consult.de)
  ~
  ~ This program is free software; you can redistribute it and/or modify it
  ~ under the terms of the GNU General Public License as published by the Free
  ~ Software Foundation; either version 3 of the License, or (at your option)
  ~ any later version.
  ~ This program is distributed in the hope that it will be useful, but WITHOUT
  ~ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  ~ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  ~ more details.
  ~
  ~ You should have received a copy of the GNU General Public License along
  ~ with this program; if not, see http://www.gnu.org/licenses/
  -->

<html>
<head>
    <title>Sentinel Toolbox Help - Colour Manipulation</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <link rel="stylesheet" href="../style.css">
</head>

<body>
<table class="header">
    <tr class="header">
        <td class="header">&nbsp;
            Colour Manipulation
        </td>

        <td class="header" align="right"><a href="../general/overview/SnapOverview.html"><img src="../images/snap_header.jpg"
                                                                                     border="0"></a></td>
    </tr>
</table>

<h3>Overview</h3>

<p>If you are opening an Image View of a data product's band or tie-point grid, the Sentinel Toolbox either loads image settings
    from the product itself (BEAM-DIMAP format only) or uses default colour settings. The <b>Colour Manipulation</b> tool
    window is used to modify the colours used in the image. Depending on the type of the source data used for the images,
    the colour manipulation window offers different editors:
</p>

<div align="center">
    <table width="640px">
        <tr>
            <td align="center" style="border-width:0"><img src="images/ColManip1BSSmall.png"/></td>
            <td align="center" style="border-width:0"><img src="images/ColManip1BTSmall.png"/></td>
        </tr>
        <tr>
            <td align="center" style="border-width:0">
                <b>A.1</b>: Editor for images of a single, spectral/geophysical band
                in <b>Sliders</b> mode
            </td>
            <td align="center" style="border-width:0">
                <b>A.2</b>: Editor for images of a single, spectral/geophysical band
                in <b>Table</b> mode
            </td>
        </tr>
        <tr>
            <td colspan="2" align="center" style="border-width:0; padding-top: 15px;"><img src="images/ColManip1BBSmall.png"/></td>
        </tr>
        <tr>
            <td colspan="2" align="center" style="border-width:0">
                <b>A.3</b>: Editor for images of a single, spectral/geophysical band
                in <b>Basic</b> mode
            </td>
        </tr>
        <tr>
            <td style="border-width:0">
                &nbsp;
            </td>
            <td style="border-width:0">
                &nbsp;
            </td>
        </tr>
        <tr>
            <td align="center" style="border-width:0"><img src="images/CM_indexCoding.png"/></td>
            <td align="center" style="border-width:0"><img src="images/CM_rgb_blue.png"/></td>
        </tr>
        <tr align="center">
            <td align="center" style="border-width:0">
                <b>B.</b>: Editor for images of a single, index-coded band
            </td>
            <td align="center" style="border-width:0">
                <b>C.</b> Editor for images using separate R,G,B channels
            </td>
        </tr>
    </table>
</div>

<p>To open the colour manipulation window, use the corresponding icon
    <img src="images/icons/ContrastStretch24.gif" alt="Contrast/Palette Window" border="0">
    icon in the main toolbar or select <b><a href="ViewMenu.html">View</a>/Tool Windows/Colour Manipulation</b>
    from the main menu.
</p>

<p>Changes in the colour manipulation window will directly become effective.</p>

<p>If the information <font color="red">Rough statistics!</font> is shown, the statistical information is computed on a
    sub-sampled level. You can click it in order to compute the accurate statistical data.
</p>


<h3>A. Editor for images of a single, spectral/geophysical band</h3>

<p>Images of a single, spectral/geophysical band use a colour palette to assign a colour to a sample value in the source
    band.
    By default, the editor is in a mode where sliders are used to modify the colour palette.
    Each slider assigns sample values to colours:
</p>

<h4>Slider Mode</h4>

<div align="center">
    <table>
        <tr>
            <td align="center" style="border-width:0"><img src="images/CM_default.png"></td>
            <td align="center" style="border-width:0"><img src="images/CM_colors.png"></td>
        </tr>
    </table>
</div>


<h5>Colour Palette Modifications</h5>

<p> As the white diagonal line above the histogram indicates, the colour palette will
    be linearly applied to the samples of the source band of the current <a href="ProductSceneView.html">Image View</a>.
    The label below the slider indicates the sample value assigned to the position of the slider in the histogram.
    By moving a slider with the mouse you can easily change its sample value. If you double-click the label,
    a text field appears where you can enter a sample value.
    By moving a slider, the colours in the palette will change accordingly. You can also click between two sliders
    in order to move the nearest slider of both under the mouse cursor.
</p>

<p>Slider colours are changed by clicking a slider. A popup window appears, where you can select the new colour.
    If you select <b>None</b>, a fully transparent slider results. In the <b>More Options</b> panels you can adjust the
    <b><a href="#nodata">No-Data Colour</a></b> and apply a
    <b><a href="#histomatch">Histogram Matching</a></b> to enhance the contrast of the final image.
</p>

<p> If you right-click on a slider, a context menu will pop up. The available actions are
    <b>Add slider</b>, <b>Remove slider</b>, <b>Center slider sample</b> and <b>Center slider colour</b>.
    Some actions may be disabled when the action cannot be performed.
</p>

<h4>Basic Mode</h4>

<p> In the basic mode it is possible to select a colour ramp from a set of predefined colour palettes.
    The selected colour ramp will be applied to the current display range.
    You can change the bounds of the display range by editing the min/max values.
    Also you can set the display bounds to min/max defined by the selected colour palette file, or set display
    bounds to the minimum and maximum data values.
</p>

<div align="center">
    <table>
        <tr>
            <td align="center" style="border-width:0"><img src="images/CM_basic.png"></td>
            <td align="center" style="border-width:0"><img src="images/CM_basic_dropdown.png"></td>
        </tr>
    </table>
</div>

<h4>Table Mode</h4>

<p>By changing the <b>Editor</b> option from <b>Sliders</b> to <b>Table</b> the sample value to colour assignment can
    be done in a table:</p>

<p align="center"><img src="images/CM_table.png"></p>

<p>Here you can enter the colour and sample values directly by clicking into a table cell.</p>

<h3>B. Editor for images of a single, index-coded band</h3>

<p>Images of a single, index-coded band, e.g. the output of a cluster analysis, look-up discrete colours from a fixed-size table:</p>

<p align="center"><img src="images/CM_indexCoding_view.png"></p>

<p>Labels and colours are simply changed by clicking into the corresponding table cell.
    In the <b>More Options</b> panels you can adjust the <b><a href="#nodata">No-Data Colour</a></b>.</p>

<h3>Editor for images using separate R,G,B channels</h3>

<p>Images using separate R,G,B channels obtain their colours from the samples of three arbitrary bands. In the
    editor, users
    can switch between the channels in order to edit the contrast stretch range and gamma value of each channel
    separately.</p>

<p align="center"><img src="images/CM_rgb.png"></p>

<p>In this mode the sliders are used for contrast stretching in each of the R,G,B channels.
    In the <b>More Options</b> panels, you can adjust the <b><a href="#nodata">No-Data Colour</a></b> and
    <b><a href="#histomatch">Histogram Matching</a></b> for the final image. The <b>Source Band</b> and <b>Gamma</b>
    options
    apply to each channel. The gamma value is used to adapt the transfer function which quantises the band's
    sample values to colour values. A gamma value of <code>0.7</code> for the blue channel enhances most
    RGB images.
</p>


<h3>Common Functions</h3>

<h4><a name="nodata">No-Data Colour</a></h4>

<p>In the <b>More Options</b> panel of all editors you can adjust the <b>No-Data Colour</b>.
    This colour will be used for no-data pixels in the source band(s).
    If you select <b>None</b>, no-data sample will be transparent in the image.</p>

<h4><a name="histomatch">Histogram Matching</a></h4>

<p>It is sometimes desirable to transform an image so that its histogram matches that of a
    specified functional form. It is possible to apply an equalized or normalized
    histogram matching to images which can often improve image quality.
</p>

<h4><a name="discrete">Discrete Colours</a></h4>

<p>Sometimes it is needed that an image is classified by value ranges. Each value range should be displayed with a
    defined colour.
    To toggle the use of discrete colours use the discrete colour checkbox. Each slider position defines the
    start or the end of a value range. The colour of an image pixel is defined by the following rule:
</p>
<pre>
            lsc = leftSliderColour
            lsv = leftSliderValue
            rsv = rightSliderValue
            vop = valueOfImagePixel
            if (vop >= lsv && vop < rsv) then pixelColor = lsc
</pre>

<p align="center">
    <b>Discrete colours 'off'</b><br><br>
    <img src="images/CM_discrete_false.png">
</p>

<p align="center">
    <b>Discrete colours 'on'</b><br><br>
    <img src="images/CM_discrete_true.png">
</p>

<h4><a name="multiassign">Multiple Assignment of the current Settings</a></h4>

<p>
    A click on the <img src="images/icons/MultiAssign24.gif"> icon opens a dialog where you can select
    the bands to which you can assign the current colour palette. If the destination band has a similar
    pixel value range, the slider positions are exacly preserved otherwise they are proportionally distributed
    over the valid range of the destination band.</p>

<h4>Import and Save of the Colour Palette</h4>

<p> Click the <img src="images/icons/document-open.png"> icon to import colour palette definition files and the <img
        src="images/icons/document-save.png"> icon to save the current colour manipulation settings.
</p>

<p>The colour palette information used for the current image can also be exported into an image file.
    Click the context menu item <a href="ExportColorLegend.html">Export Colour Legend</a>
    over an open image view in order export the colour legend.
</p>

<p>The colour palette can be also exported as a <a href="ExportColorPalette.html">Colour Palette Table</a>.
    Choose from the <b>File</b> menu <b>Colour Palette</b> to export the table as a *.csv or *.txt file.
</p>

<p class="inote">Note: The Sentinel Toolbox has a couple of predefined colour palettes. They are stored
    in <code><i>user-home</i>/.snap/snap-ui/auxdata/color-palettes</code>. For convenience, the
    import/export file choosers in the colour manipulation window dialog use this folder by default.
</p>

<h4><a name="autoadjust">Slider Auto-Adjustment</a></h4>

<p>
    A click on the <img src="images/icons/Auto95Percent24.gif">
    icon adjusts the sliders to cover 95% of all pixels in the band.
</p>

<p>
    A click on the <img src="images/icons/Auto100Percent24.gif">
    icon adjusts the sliders to cover 100% (the full range) of all pixels in the band.
</p>

<p>
    A click on the <img src="images/icons/EvenDistribution.gif">
    icon distributes the inner sliders evenly between the first and the last slider.
</p>

<h4><a name="zommingintohisto">Zooming into the histogram</a></h4>

<p>
    Click on the <img src="images/icons/ZoomIn24V.gif">
    icon to zoom in vertically or on the
    <img src="images/icons/ZoomIn24H.gif">
    icon to
    zoom into the histogram horizontally.
</p>

<h4><a name="zommingoutofhisto">Zooming out of the histogram</a></h4>

<p> Click on the <img src="images/icons/ZoomOut24V.gif">
    icon to zoom out vertically or on the
    <img src="images/icons/ZoomOut24H.gif">icon
    to zoom out of the histogram horizontally.
</p>

<h4>Logarithmic display</h4>

<p> With a click on the button <img src="images/icons/LogDisplay24.png"> it is possible
    to distribute the colour palette sliders in a logarithmic manner (right image in the figure below),
    causing lower values to be displayed with smaller colour steps.
</p>

<div align="center">
    <table>
        <tr>
            <td align="center" style="border-width:0"><img src="images/CM_Lin_Slider.png"><br>linear colour ramp</td>
            <td align="center" style="border-width:0"><img src="images/CM_Log_Slider.png"><br>logarithmic colour ramp</td>
        </tr>
    </table>
</div>


<h4>Reset</h4>

<p>The reset icon <img src="images/icons/Undo24.gif"> is used to revert the window to contain default values.
</p>

<h4>Extra information</h4>

<p>The information icon <img src="images/icons/Information24.gif"> is used to toggle the visibility of the extra
    information area.
</p>

<h4><a name="contexthelp">Context help</a></h4>

<p> The help icon <img src="images/icons/Help22.png"> opens the Help for the current context.
</p>


<hr>
</body>
</html>

<!--page visited by UK-->
